#ifndef _ESC_TABLE_H_
#define _ESC_TABLE_H_

/*
 * Essential-C - Essential C Libraries for Developers
 * Copyright (c) 2004-2008 Tom Bradford <tom@tbradford.org>
 *
 * Permission is hereby granted, free of charge, to any person obtaining a 
 * copy of this software and associated documentation files (the "Software"),
 * to deal in the Software without restriction, including without limitation
 * the rights to use, copy, modify, merge, publish, distribute, sublicense,
 * and/or sell copies of the Software, and to permit persons to whom the
 * Software is furnished to do so, subject to the following conditions:
 * 
 * The above copyright notice and this permission notice shall be included
 * in all copies or substantial portions of the Software.
 * 
 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS
 * OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
 * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL
 * THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
 * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING 
 * FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER 
 * DEALINGS IN THE SOFTWARE.
 */

/**
 * Implements a key/value table utilizing a linear hashing algorithm.
 * Linear hashing leverages linear growth rather than geometric, and
 * so provides very good retrieval times as well as expansion that
 * requires only minimal rearrangement of buckets.  This implementation
 * does not bother to shrink the table, as the expectation would be
 * that the buckets will continue to be reused.
 * 
 * Note: These functions are NOT thread-safe.  You must manage your
 * own mutexes if you plan on safely threading a Table or Table-derived
 * structures. 
 */

#include <stdbool.h>

#include "esc_common.h"
#include "esc_mem.h"

#ifdef __cplusplus
extern "C" {
#endif // __cplusplus


#define ESC_TABLE_REMOVE    -1

/** Incomplete type for Table instances */
typedef struct esc_table_t esc_table_t;

/** Function type for Table value hash calculations */
typedef int esc_table_hash_t(esc_table_t* table, void* key);

/** Function type for Table value comparisons */
typedef int esc_table_compare_t(esc_table_t* table, void* key1, void* key2);

/** Function type for Table iteration callbacks */
typedef esc_status_t esc_table_iterator_t(esc_table_t* table, void* key, 
                                          void* item, void* context);

/** Create a Table instance */
esc_table_t* esc_table_new(esc_mem_t* mem);

/** The default hash function for Tables (operates on C strings) */
int esc_table_hash_string(esc_table_t* table, char* key);

/** The default compare function for Tables (operates on C strings) */
int esc_table_compare_string(esc_table_t* table, char* key1, char* key2);

/** Sets the hash function for the Table */
void esc_table_setHashFunction(esc_table_t* table, 
                               esc_table_hash_t* hashFunction);

/** Returns the hash function for the Table */
esc_table_hash_t* esc_table_getHashFunction(esc_table_t* table);

/** Sets the compare function for the Table */
void esc_table_setCompareFunction(esc_table_t* table, 
                                  esc_table_compare_t* compareFunction);

/** Returns the compare function for the Table */
esc_table_compare_t* esc_table_getCompareFunction(esc_table_t* table);

/** Associate the specified key with the provided item */
void esc_table_setItem(esc_table_t* table, void* key, void* item);

/** Returns the item associated with the specified key */
void* esc_table_getItem(esc_table_t* table, void* key);

/** Removes the item associated with the specified key */
void* esc_table_removeItem(esc_table_t* table, void* key);

/** Removes all items from the Table */
void esc_table_removeAll(esc_table_t* table);

/** Returns the total number of items in the Table */
int esc_table_getSize(esc_table_t* table);

/** Returns whether or not the List is empty */
bool esc_table_isEmpty(esc_table_t* table);

/** Iterates over the items of the Table, performing a callback for each */
esc_status_t esc_table_iterate(esc_table_t* list, 
                               esc_table_iterator_t* iterator, void* context);


#ifdef __cplusplus
}
#endif // __cplusplus

#endif // _ESC_TABLE_H_
